<div xmlns:ext="http://www.extjs.com" class="body-wrap"><div class="inheritance res-block"><pre class="res-block-inner"><a href="output/Ext.data.Association.html" ext:member="" ext:cls="Ext.data.Association">Association</a>
  <img src="resources/elbow-end.gif">BelongsToAssociation</pre></div><h1>Class <a href="source/BelongsToAssociation.html#cls-Ext.data.BelongsToAssociation">Ext.data.BelongsToAssociation</a></h1><table cellspacing="0"><tr><td class="label">Package:</td><td class="hd-info">Ext.data</td></tr><tr><td class="label">Defined In:</td><td class="hd-info"><a href="source/BelongsToAssociation.html#cls-Ext.data.BelongsToAssociation">BelongsToAssociation.js</a></td></tr><tr><td class="label">Class:</td><td class="hd-info"><a href="source/BelongsToAssociation.html#cls-Ext.data.BelongsToAssociation">BelongsToAssociation</a></td></tr><tr><td class="label">Extends:</td><td class="hd-info"><a href="output/Ext.data.Association.html" ext:cls="Ext.data.Association" ext:member="">Association</a></td></tr></table><div class="description"><p>Represents a many to one association with another model. The owner model is expected to have
a foreign key which references the primary key of the associated model:</p>
<pre><code><b>var</b> Category = Ext.regModel(<em>'Category'</em>, {
    fields: [
        {name: <em>'id'</em>,   type: <em>'int'</em>},
        {name: <em>'name'</em>, type: <em>'string'</em>}
    ]
});

<b>var</b> Product = Ext.regModel(<em>'Product'</em>, {
    fields: [
        {name: <em>'id'</em>,          type: <em>'int'</em>},
        {name: <em>'category_id'</em>, type: <em>'int'</em>},
        {name: <em>'name'</em>,        type: <em>'string'</em>}
    ],

    associations: [
        {type: <em>'belongsTo'</em>, model: <em>'Category'</em>}
    ]
});</code></pre>
<p>In the example above we have created models for Products and Categories, and linked them together
by saying that each Product belongs to a Category. This automatically links each Product to a Category
based on the Product's category_id, and provides new functions on the Product model:</p>
<p><u>Generated getter function</u></p>
<p>The first function that is added to the owner model is a getter function:</p>
<pre><code><b>var</b> product = <b>new</b> Product({
    id: 100,
    category_id: 20,
    name: <em>'Sneakers'</em>
});

product.getCategory(<b>function</b>(category, operation) {
    <i>//<b>do</b> something <b>with</b> the category object</i>
    alert(category.get(<em>'id'</em>)); <i>//alerts 20</i>
}, this);</code></pre>
<p>The getCategory function was created on the Product model when we defined the association. This uses the
Category's configured <a href="output/Ext.data.Proxy.html" ext:cls="Ext.data.Proxy">proxy</a> to load the Category asynchronously, calling the provided
callback when it has loaded.</p>
<p>The new getCategory function will also accept an object containing success, failure and callback properties
- callback will always be called, success will only be called if the associated model was loaded successfully
and failure will only be called if the associatied model could not be loaded:</p>
<pre><code>product.getCategory({
    callback: <b>function</b>(category, operation) {}, <i>//a <b>function</b> that will always be called</i>
    success : <b>function</b>(category, operation) {}, <i>//a <b>function</b> that will only be called <b>if</b> the load succeeded</i>
    failure : <b>function</b>(category, operation) {}, <i>//a <b>function</b> that will only be called <b>if</b> the load did not succeed</i>
    scope   : this <i>//optionally pass <b>in</b> a scope object to execute the callbacks <b>in</b></i>
});</code></pre>
<p>In each case above the callbacks are called with two arguments - the associated model instance and the 
<a href="output/Ext.data.Operation.html" ext:cls="Ext.data.Operation">operation</a> object that was executed to load that instance. The Operation object is
useful when the instance could not be loaded.</p>
<p><u>Generated setter function</u></p>
<p>The second generated function sets the associated model instance - if only a single argument is passed to
the setter then the following two calls are identical:</p>
<pre><code><i>//this call</i>
product.setCategory(10);

<i>//is equivalent to this call:</i>
product.set(<em>'category_id'</em>, 10);</code></pre>
<p>If we pass in a second argument, the model will be automatically saved and the second argument passed to
the owner model's <a href="output/Ext.data.Model.html#Ext.data.Model-save" ext:member="save" ext:cls="Ext.data.Model">save</a> method:</p>
<pre><code>product.setCategory(10, <b>function</b>(product, operation) {
    <i>//the product has been saved</i>
    alert(product.get(<em>'category_id'</em>)); <i>//now alerts 10</i>
});

<i>//alternative syntax:</i>
product.setCategory(10, {
    callback: <b>function</b>(product, operation), <i>//a <b>function</b> that will always be called</i>
    success : <b>function</b>(product, operation), <i>//a <b>function</b> that will only be called <b>if</b> the load succeeded</i>
    failure : <b>function</b>(product, operation), <i>//a <b>function</b> that will only be called <b>if</b> the load did not succeed</i>
    scope   : this <i>//optionally pass <b>in</b> a scope object to execute the callbacks <b>in</b></i>
})</code></pre>
<p><u>Customisation</u></p>
<p>Associations reflect on the models they are linking to automatically set up properties such as the
<a href="output/Ext.data.BelongsToAssociation.html#Ext.data.BelongsToAssociation-primaryKey" ext:member="primaryKey" ext:cls="Ext.data.BelongsToAssociation">primaryKey</a> and <a href="output/Ext.data.BelongsToAssociation.html#Ext.data.BelongsToAssociation-foreignKey" ext:member="foreignKey" ext:cls="Ext.data.BelongsToAssociation">foreignKey</a>. These can alternatively be specified:</p>
<pre><code><b>var</b> Product = Ext.regModel(<em>'Product'</em>, {
    fields: [...],

    associations: [
        {type: <em>'belongsTo'</em>, model: <em>'Category'</em>, primaryKey: <em>'unique_id'</em>, foreignKey: <em>'cat_id'</em>}
    ]
});</code></pre>
<p>Here we replaced the default primary key (defaults to 'id') and foreign key (calculated as 'category_id')
with our own settings. Usually this will not be needed.</p></div><div class="hr"></div><a id="Ext.data.BelongsToAssociation-configs"></a><h2>Config Options</h2><table cellspacing="0" class="member-table"><tbody><tr><th colspan="2" class="sig-header">Config Options</th><th class="msource-header">Defined By</th></tr><tr class="config-row  inherited"><td class="micon"><a href="#expand" class="exi">&nbsp;</a></td><td class="sig"><a id="Ext.data.Association-associatedModel"></a><b><a href="source/Association.html#cfg-Ext.data.Association-associatedModel">associatedModel</a></b> : String<div class="mdesc">The string name of the model that is being associated with. Required</div></td><td class="msource"><a href="output/Ext.data.Association.html#associatedModel" ext:member="#associatedModel" ext:cls="Ext.data.Association">Association</a></td></tr><tr class="config-row expandable "><td class="micon"><a href="#expand" class="exi">&nbsp;</a></td><td class="sig"><a id="Ext.data.BelongsToAssociation-foreignKey"></a><b><a href="source/BelongsToAssociation.html#cfg-Ext.data.BelongsToAssociation-foreignKey">foreignKey</a></b> : String<div class="mdesc"><div class="short">The name of the foreign key on the owner model that links it to the associated
model. Defaults to the lowercased name...</div><div class="long">The name of the foreign key on the owner model that links it to the associated
model. Defaults to the lowercased name of the associated model plus "_id", e.g. an association with a
model called Product would set up a product_id foreign key.</div></div></td><td class="msource">BelongsToAssociation</td></tr><tr class="config-row expandable "><td class="micon"><a href="#expand" class="exi">&nbsp;</a></td><td class="sig"><a id="Ext.data.BelongsToAssociation-getterName"></a><b><a href="source/BelongsToAssociation.html#cfg-Ext.data.BelongsToAssociation-getterName">getterName</a></b> : String<div class="mdesc"><div class="short">The name of the getter function that will be added to the local model's prototype. 
Defaults to 'get' + the name of t...</div><div class="long">The name of the getter function that will be added to the local model's prototype. 
Defaults to 'get' + the name of the foreign model, e.g. getCategory</div></div></td><td class="msource">BelongsToAssociation</td></tr><tr class="config-row  inherited"><td class="micon"><a href="#expand" class="exi">&nbsp;</a></td><td class="sig"><a id="Ext.data.Association-ownerModel"></a><b><a href="source/Association.html#cfg-Ext.data.Association-ownerModel">ownerModel</a></b> : String<div class="mdesc">The string name of the model that owns the association. Required</div></td><td class="msource"><a href="output/Ext.data.Association.html#ownerModel" ext:member="#ownerModel" ext:cls="Ext.data.Association">Association</a></td></tr><tr class="config-row  inherited"><td class="micon"><a href="#expand" class="exi">&nbsp;</a></td><td class="sig"><a id="Ext.data.Association-primaryKey"></a><b><a href="source/Association.html#cfg-Ext.data.Association-primaryKey">primaryKey</a></b> : String<div class="mdesc">The name of the primary key on the associated model. Defaults to 'id'</div></td><td class="msource"><a href="output/Ext.data.Association.html#primaryKey" ext:member="#primaryKey" ext:cls="Ext.data.Association">Association</a></td></tr><tr class="config-row expandable "><td class="micon"><a href="#expand" class="exi">&nbsp;</a></td><td class="sig"><a id="Ext.data.BelongsToAssociation-setterName"></a><b><a href="source/BelongsToAssociation.html#cfg-Ext.data.BelongsToAssociation-setterName">setterName</a></b> : String<div class="mdesc"><div class="short">The name of the setter function that will be added to the local model's prototype.
Defaults to 'set' + the name of th...</div><div class="long">The name of the setter function that will be added to the local model's prototype.
Defaults to 'set' + the name of the foreign model, e.g. setCategory</div></div></td><td class="msource">BelongsToAssociation</td></tr></tbody></table><a id="Ext.data.BelongsToAssociation-props"></a><h2>Public Properties</h2><table cellspacing="0" class="member-table"><tbody><tr><th colspan="2" class="sig-header">Property</th><th class="msource-header">Defined By</th></tr><tr class="property-row  inherited"><td class="micon"><a href="#expand" class="exi">&nbsp;</a></td><td class="sig"><a id="Ext.data.Association-associatedName"></a><b><a href="source/Association.html#prop-Ext.data.Association-associatedName">associatedName</a></b> : String<div class="mdesc">The name of the model is on the other end of the association (e.g. if a User model hasMany Orders, this is 'Order')</div></td><td class="msource"><a href="output/Ext.data.Association.html#associatedName" ext:member="#associatedName" ext:cls="Ext.data.Association">Association</a></td></tr><tr class="property-row  inherited"><td class="micon"><a href="#expand" class="exi">&nbsp;</a></td><td class="sig"><a id="Ext.data.Association-ownerName"></a><b><a href="source/Association.html#prop-Ext.data.Association-ownerName">ownerName</a></b> : String<div class="mdesc">The name of the model that 'owns' the association</div></td><td class="msource"><a href="output/Ext.data.Association.html#ownerName" ext:member="#ownerName" ext:cls="Ext.data.Association">Association</a></td></tr></tbody></table><a id="Ext.data.BelongsToAssociation-methods"></a><h2>Public Methods</h2><div class="no-members">This class has no public methods.</div><a id="Ext.data.BelongsToAssociation-events"></a><h2>Public Events</h2><div class="no-members">This class has no public events.</div></div>